Distributor Knowledge Base

TABLE OF CONTENTS

Reservation API Introduction
Key Functionalities of the Reservation API
Reservation Flow overview

Reservation API Introduction

This section introduces the various Reservation APIs that enable distributors to facilitate real-time bookings, cancellations, modifications, and queries. These APIs ensure seamless communication between distributors and hotel suppliers, providing up-to-date information and enabling efficient reservation management. To create a reservation using DerbySoft APIs, it is required to first perform a Live Check to ensure that the rate and availability are accurate and up-to-date. Following the live check, a Prebook must be executed to confirm the final availability before proceeding with the actual booking. Once these steps are completed, the Book API can be used to finalize the reservation. Additionally, while the Reservation APIs are designed for generic use by all distributors, some fields will be specific to certain distribution models offered by DerbySoft. Exchange distribution and Corporate distribution will have specific fields tailored to support these different models. These specific fields will be clearly highlighted in the schemas, making it easier for distributors to implement the APIs correctly.

Distributors can implement the following Reservation API functionalities to integrate with our system, supporting their booking operations:

Live Check: This API allows distributors to check real-time availability and get a list of available rooms and rates from the hotel supplier’s system.
Prebook: Before finalizing a booking, distributors must use this API to perform a final check, verifying availability and rates in real time.
Book: This API enables distributors to complete a booking by sending a request to the hotel supplier's system for real-time confirmation.
Modify: This optional API allows distributors to modify an existing booking by sending a request to the supplier's system for real-time confirmation of the change. If a supplier cannot support modifications, this will follow a cancel-rebook strategy. Note that distributors working with Disney must implement this API.
Cancel: This API allows distributors to cancel existing bookings, ensuring real-time cancellation confirmation from the hotel supplier’s system.
Query Reservation List: This optional API allows distributors to query and retrieve a list of existing bookings, enabling efficient tracking of reservations.
Query Reservation Detail: This optional API allows distributors to retrieve detailed information about existing bookings, including the status of time-sensitive reservations.

Key Functionalities of the Reservation API

Real-Time Reservation Management: Distributors can manage bookings in real time, ensuring accurate reservations by interacting directly with hotel suppliers' systems for availability, bookings, modifications, and cancellations.
Live Availability and Rates Check: Using the Live Check API, distributors can query real-time availability and rates, ensuring they only show current, available options to customers.
Prebooking Verification: The Prebook API allows distributors to double-check availability and rates before finalizing a reservation, ensuring no discrepancies during the booking process.
Booking Confirmation: The Book API enables distributors to finalize reservations by providing real-time confirmation, ensuring that the booking is successfully processed and confirmed within the hotel’s system.
Booking Modifications: The Modify API allows distributors to update existing bookings, with real-time confirmation on modifications from the hotel’s system. If the supplier or you cannot support direct changes, you could follow a cancel-rebook strategy.
Real-Time Cancellation: The Cancel API ensures that distributors can cancel bookings, receiving immediate confirmation from the supplier’s system.
Reservation Querying and Flexible Parameters: The Query Reservation List and Query Reservation Detail APIs allow distributors to query and retrieve detailed information about existing bookings, aiding in effective reservation management and tracking. These APIs are optional but useful for comprehensive booking oversight. Distributors can also utilize flexible query parameters, such as date ranges, reservation status, and other criteria, to filter and refine the data for more granular control over the information retrieved.
Scalable Reservation Management: The Reservation APIs are designed to handle large volumes of real-time data, ensuring distributors can scale their operations to accommodate growing customer bases without sacrificing performance.

Reservation Flow overview

Live check API

The Live Check API allows distributors to query real-time availability from hotel suppliers or DerbySoft cache, ensuring they receive up-to-date information on all available rooms and rates. This functionality is essential for ensuring that the data presented to customers reflects the current status of hotel inventory. If a hotel supplier does not support the live check function, the check will be done in the DerbySoft cache to provide availability data. Additionally, the Live Check API supports a maximum stay of up to 61 days, depending on the supplier’s capabilities. This flexibility enables distributors to check long-term availability and offer extended stay options to their customers, provided the supplier supports this duration.

The implementation of this API is a mandatory step in the booking flow, ensuring accurate and timely availability information before proceeding with further reservation actions.

POST /availability HTTP/1.1
URL: {endpoint}/availability
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Live Check Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	MaxLength: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	MaxLength: 20 Version of API	v4
2	@token	string	Y	MaxLength: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers contain the following characters only: 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	2
2	@adultCount	integer	Y	Adult count per room	1
2	@childCount	integer	N	Child count per room	2
2	@childAges	array	N	Child ages for each child, array size MUST be the same as a child count.	[ 4, 8 ]
1	productCandidate	object	N	/	/
2	@roomId	string	N	Room ID in supplier's system	K1D
2	@rateId	string	N	Rate ID in supplier's system	ODAD01
1	iata	string	N	IATA of distributor	/
1	loyaltyAccount	object	N	/	/
2	@programCode	string	Y	Loyalty program code of the supplier	BW
2	@accountId	string	Y	Loyalty program account ED	1234567890123457
1	corpAccount	object	N	/	/
2	@corpProgramCode	string	Y	Corporate Hotel Program of hotel supplier	CR
2	@corpId	string	Y	Corporate ID in the program account	A-1232
1	isAfterPromotion	boolean	N	The flag indicates calculating the available room rates with the promotion rules or not. TRUE means checking the availability under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
1	promoteCode	string	N	Promote code defined by the hotel, is an optional field when you want to request the promotion rates (isAfterPromotion=true). If promote code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/
1	bookingChannel	string	N	Sub-distributor ID	/
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/
1	onlyExactMatch	boolean	N	Only return the rate plans that are allocated to the corpCode and do not return any other public rate plans. Note: If the corpCodes are not specified, the field will be ignored.	false
1	corpCodes	array[string]	N	Notes: 1. It depends on the corporate code mapping between Go Distributors and hotel suppliers. If the mapping is not in place and corporate codes are passed, an error will occur. 2. The maximum number of corpCodes allowed is 10.	["CORPA", "CORPB"]

Live Check Request Example

Live Check Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "roomCriteria": {
      "roomCount": 2,
      "adultCount": 1,
      "childCount": 2,
      "childAges": [
        4,
        8
      ]
    },
    "productCandidate": {
      "roomId": "K1D",
      "rateId": "ODAD01"
    },
    "iata": "string",
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "isAfterPromotion": false,
    "promoteCode": "string",
    "bookingChannel": "string",
    "extensions": {
      "sendProductInformation": "true",
      "key2": "value2"
    },
    "onlyExactMatch": false,
    "corpCodes": [
      "CORPA",
      "CORPB"
    ]
  }

Live Check Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	MaxLength: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	MaxLength: 20 Version of API	v4
2	@token	string	Y	MaxLength: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers contain the following characters only: 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	2
2	@adultCount	integer	Y	Adult count per room	1
2	@childCount	integer	N	Child count per room	2
2	@childAges	array	N	Child ages for each child, array size MUST be the same as the child count/	[ 4, 8 ]
1	productCandidate	object	N	/	/
2	@roomId	string	N	Room ID in supplier system	K1D
2	@rateId	string	N	Rate ID in supplier system	ODAD01
1	iata	string	N	IATA of distributor	/
1	roomRates		Y	Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
2	@inventory	integer	Y	Available inventory count according to request criteria	1
2	@isAfterPromotion	boolean	N	The flag indicates calculating the available room rates with the promotion rules or not. Default is false if null TRUE means to check the availability that is under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
2	@promoteCode	string	N	The code for the promotion applied to this rate, It's required when isAfterPromotion = true.	discount001
2	@roomId	string	Y	Room ID in supplier system	10000101
2	@roomName	string	N	Max length: 256	King Room
2	@roomDescription	string	N	/	Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.
2	@rateId	string	Y	Rate ID in supplier system	BAR
2	@rateName	string	N	Max length: 256	Best Available Rate
2	@rateDescription	string	N	/	Begin your day with a hearty meal
2	@connectionType	enum	N	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
2	corpCodes	array[string]	N	/	["CORPA", "CORPB"]
2	isLoyaltyEligible	boolean	N	isLoyaltyEligible(value: true/false) indicates whether a rate plan allows customers to earn hotel loyalty points.	false
2	commission	object	N	The commission indicates to the distributor the amount they can earn as compensation.	/
3	@value	number	Y	Commission value	10
3	@type	enum	Y	Commission type Enum: [Percent, Amount]	Percent
2	@currency	string	Y	Currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	The daily rate for a single room, excluding taxes and fees.	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	The daily rate for a single room, including taxes and fees.	[ 110, 110, 130 ]
2	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
3	@amountBeforeTax	number	N	/	600
3	@amountAfterTax	number	N	/	700
2	@mealPlan	string	N	For meal plan code, refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
2	guarantee	object	N	Guarantee information for this room rate.	/
3	@guaranteeType	string	Y	The type of guarantee method, refer to the standard guarantee type list.	CCG
2	fees	array[object]	N	Fee or tax by date range.	/
3	dateRange	object	Y	/	/
4	@startDate	string	Y	Start date of date range, format with yyyy-MM-dd	2018-01-01
4	@endDate	string	Y	End date of date range, format with yyyy-MM-dd	2018-01-04
3	fee	object	Y	/	/
4	@name	string	Y	Pattern: \w[\w\d]+	Service Charge
4	@type	enum	Y	The fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	N	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	3
2	cancelPolicy	object	N	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show/	/
3	@code	string	Y	Max Length: 128 Code of cancel policy	AD100P_100P
3	@description	string	N	Max Length: 1024 the description of the cancel policy	Non Refundable
3	cancelPenalties	array[object]	Y	Detail about the cancel Penalty	/
4	@noShow	boolean	Y	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
4	@cancellable	boolean	N	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
4	cancelDeadline		N	/	/
5	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
5	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
5	@offsetTimeValue	number	N	The number of offset times with the time unit.	/
5	@deadline	string	N	local deadline time allowed for cancellation, like 4 PM, or 6 PM.	/
4	penaltyCharge	/	/	/	/
5	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
5	@nights	number	N	Exists if the penalty charge is based on the night, like the first night.	/
5	@amount	number	N	Exists if the penalty charge is a flat charge, like USD 30.00.	/
5	@percent	number	N	Exists if the penalty charge is percent, like 15.5 means 15.5%.	/
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Live Check Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Standard",
      "corpCodes": [
          "CORPA",
          "CORPB"
        ],
      "isLoyaltyEligible": true,
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "paymentType": "PayLater",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Exchange",
      "commission": {
        "value": 10,
        "type": "Percent"
      },
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateId": "ODAD01",
      "rateName": "Standard Rate",
      "rateDescription": "Standard Rate Includes Breakfast",
      "connectionType": "Exchange",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "suggestedTotalPrice": {
        "amountBeforeTax": 600,
        "amountAfterTax": 700
      },
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "collectBy": "Distributor",
            "effectivePerson": 0
          }
        },
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "City Tax",
            "type": "Exclusive",
            "amount": 5,
            "amountType": "Fix",
            "chargeType": "PerPersonPerNight",
            "collectBy": "Property",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 0,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response(HTTP Status 403)

{
  "error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

PreBook API

The Prebook API allows distributors to perform a final check on the availability and rates of a selected product before proceeding with a booking. This step ensures that the room and rate are still available and accurate at the time of booking, reducing the risk of discrepancies or overbooking. If the hotel supplier supports it, the Prebook API can handle reservations with a maximum stay length of up to 61 days. By executing this final check, distributors can confidently proceed with the booking process, knowing that the selected room and rate remain available. This API is essential for ensuring a smooth and reliable booking experience for both distributors and customers..

POST /reservation/prebook HTTP/1.1
URL: {endpoint}/reservation/prebook
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

PreBook Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of hotel supplier in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds	/	Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs. PS: If distributors don't generate reservation IDs during the stage, you can fill in a blank value in the request for the field like distributorResId="", but the null value is not accepted since it's a mandatory field.	C2084DFL0
1	iata	string	N	IATA	/
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	contactPerson	object	Y	/	/
2	@firstName	string	Y	First Name	James
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	/
2	@adultCount	integer	Y	Adult count per room	/
2	@childCount	integer	N	Child count per room	/
2	@childAges	array	N	Child ages for each child, array size MUST be the same as the child count/	/
1	total	object	Y	/	/
2	@amountBeforeTax	number	N	abbr. ABT The total room rate for the entire reservation, not including taxes and fees. It's required if AAT is not provided	640
2	@amountAfterTax	number	N	abbr. AAT The total room rate for the entire reservation, including taxes and fees. It's required if ABT is not provided	700
1	payment	object	No	If the credit card information is not going to be passed to the property, this information will be ignored.	/
2	@cardType	string	N	If the payment card type is not specified, it will be treated as the default value "CC" which stands for Credit Card. The type value can be one of the options listed below. CC: Credit Card VCC: Virtual Credit Card CBILL: Central Bill	CC
2	@cardCode	string	Y	VI, MC, AX, etc. Card Code	VI
2	@cardNumber	string	Y	Credit card number	4111111111111111
2	@cardHolderName	string	Y	Cardholder name	Sherlock Holmes
2	@expireDate	string	Y	It should be 2 digits for the month, and 2 digits for the year, as "MMYY"	0119
2	@securityCode	string	N	Card verification value	123
2	@vccEffectiveDate	string	N	The effective date of the VCC. Format: yyyy-MM-dd	2025-06-30
2	@vccInvalidDate	string	N	The date when the VCC expires. Format: yyyy-MM-dd	2025-07-30
2	@vccAmountOnCard	number	N	The limit amount for the VCC	1000.00
2	@vccCurrency	string	N	The currency code [ISO-4217] of the amount	USD

1	loyaltyAccount	object	N	/	/
2	@programCode	string	Y	Loyalty program code of the supplier	BW
2	@accountId	string	Y	Loyalty program account ID	1234567890123457
1	corpAccount	object	N	/	/
2	@corpProgramCode	string	Y	Corporate Hotel Program of hotel supplier	CR
2	@corpId	string	Y	Corporate ID in the program account	A-1232
1	promoteCode	string	N	Promotion code defined by the hotel, the promotion code is required if making a reservation under the promotion	/
1	guests	array[object]	Y	/	/
2	@firstName	string	Y	First Name	James
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
2	@age	integer	N	Age of guest	/
2	@gender	enum	N	Gender of guest Enum: [Male,Female ]	Male
2	@birthday	string	N	Birthday of guest format with yyyy-MM-dd	1970-12-20
2	@type	string	N	Type of guest Adult, Child, or Infant Enum: [ Adult, Child, Infant ]	/
2	@index	integer	N	Indicate which guests will be allocated to which room. For one room reservation, the room index is 1 for all guests. For multi-room reservations, the index starts from 1 and the max room index is equal to the number of booked rooms.	index = 1, Indicate the guest will be allocated to the first room. index = 2, Indicate the guest will allocate to the second room.
2	@extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format).	/
1	comments	array[string]	N	/	[ "no smoking", "high floor" ]
1	roomRates	array[object]	Y	Min Items: 1 Max Items: 1 meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
2	@roomId	string	Y	Room ID in supplier's system	10000101
2	@rateId	string	Y	Rate ID in supplier's system	123456
2	@currency	string	Y	Currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	abbr. ABT The daily amount of rate without tax and fee It's required if AAT is not provided	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	abbr. AT The daily amount of rate with tax and fee It's required if ABT is not provided	[ 110, 110, 130 ]
2	@mealPlan	string	N	Meal plan code, refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
2	rguarantee	object	N	Guarantee information for this room rate.	/
3	@guaranteeType	string	Y	The type of guarantee method, refer to the standard guarantee type list.	CCG
2	fees	array[object]	N	Fee or tax by date range.	/
3	dateRange	object	Y	/	/
4	@startDate	string	Y	Start date of date range, format with yyyy-MM-dd	2018-01-01
4	@endDate	string	Y	End date of date range, format with yyyy-MM-dd	2018-01-04
3	fees/fee		Y	/	/
4	@name	string	Y	Pattern: \w[\w\d]+	Service Charge
4	@type	enum	Y	The fee or tax is included in the amount before tax or not Enum: [ Inclusive, Exclusive ]	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	N	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	/
2	cancelPolicy	object	N	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show	/
3	@code	string	Y	MaxLength: 128 code of cancel policy	AD100P_100P
3	@description	string	N	MaxLength: 1024 the description of the cancel policy	Non Refundable
3	cancelPenalties		Y	Detail about the cancel Penalty	/
4	@noShow	boolean	Y	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
4	@cancellable	boolean	N	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
4	cancelDeadline	/	/	/	/
5	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
5	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
5	@offsetTimeValue	number	N	The number of offset times with the time unit/	/
5	@deadline	string	N	local deadline allowed for cancellation, like 4 PM, 6 PM.	/
4	penaltyCharge	/	/	/	/
5	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
5	@nights	number	N	Exists if the penalty charge is based on the night, like the first night	/
5	@amount	number	N	Exists if the penalty charge is a flat charge, like USD 30.00	/
5	@percent	number	N	Exists if the penalty charge is percent, like 15.5 means 15.5%	/
1	bookingChannel	string	N	Sub-distributor ID	/
1	productAddons	array[object]	N	/	/
2	@type	string	Y	product addon type	/
2	@code	string	Y	product addon code	/
2	@date	string	Y	format with yyyy-MM-dd	2022-01-01
2	@quantity	integer	Y	/	1
2	@officeId	string	N	/	/
2	rate	object	N	/	/
3	ageQualifyingType	object	N	/	/
3	@type	enum	Y	Enum: [Adult, Child]	Adult
3	@minAge	integer	Y	/	18
3	@maxAge	integer	Y	/	18
2	currency	string	Y	/	USD
2	amountBeforeTax	number	N	/	123.23
2	amountAfterTax	number	N	/	134.34
1	corpCode	string	N	Corporate code in Distributor's system Note: This field is primarily used by Travel Management Companies (TMCs) distributors.	D_XXX
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

PreBook Request Example

PreBook Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0"
    },
    "iata": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "contactPerson": {
      "firstName": "Thomas",
      "lastName": "Hintz",
      "email": "Thomas.Hintz@yahoo.com",
      "phone": "260-975-4091",
      "address": "3946 Freddy Locks"
    },
    "roomCriteria": {
      "roomCount": 1,
      "adultCount": 2,
      "childCount": 1,
      "childAges": [
        5
      ]
    },
    "total": {
      "amountBeforeTax": 640,
      "amountAfterTax": 700
    },
    "payment": {
      "cardType": "CC",
      "cardCode": "VI",
      "cardNumber": "4111111111111111",
      "cardHolderName": "Sherlock Holmes",
      "expireDate": "0119",
      "securityCode": "123",
      "vccEffectiveDate": "2018-01-01",
      "vccInvalidDate": "2018-01-02",
      "vccAmountOnCard": 502.19,
      "vccCurrency": "USD"
    },
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "promoteCode": "string",
    "guests": [
      {
        "firstName": "Thomas",
        "lastName": "Hintz",
        "email": "Thomas.Hintz@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 32,
        "gender": "Male",
        "birthday": "1990-01-01",
        "type": "Adult",
        "index": 1,
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "firstName": "Hillary",
        "lastName": "Ullrich",
        "email": "Xavier.Lind49@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 28,
        "gender": "Female",
        "birthday": "1994-01-01",
        "type": "Adult",
        "index": 1
      },
      {
        "firstName": "Alex",
        "lastName": "Hintz",
        "age": 5,
        "type": "Child",
        "index": 1
      }
    ],
    "comments": [
      "no smoking",
      "high floor"
    ],
    "roomRates": [
      {
        "roomId": "K1D",
        "rateId": "ODAD01",
        "currency": "USD",
        "amountBeforeTax": [
          100,
          100,
          120
        ],
        "amountAfterTax": [
          110,
          110,
          130
        ],
        "mealPlan": "RO",
        "paymentType": "PayNow",
        "guarantee": {
          "guaranteeType": "CCG"
        },
        "fees": [
          {
            "dateRange": {
              "startDate": "2018-01-01",
              "endDate": "2018-01-04"
            },
            "fee": {
              "name": "Service Charge",
              "type": "Exclusive",
              "amount": 10,
              "amountType": "Percent",
              "chargeType": "PerRoomPerNight",
              "paymentType": "PayNow",
              "collectBy": "Distributor",
              "effectivePerson": 0
            }
          },
          {
            "dateRange": {
              "startDate": "2018-01-01",
              "endDate": "2018-01-04"
            },
            "fee": {
              "name": "City Tax",
              "type": "Exclusive",
              "amount": 5,
              "amountType": "Fix",
              "chargeType": "PerPersonPerNight",
              "paymentType": "PayLater",
              "collectBy": "Property",
              "effectivePerson": 0
            }
          }
        ],
        "cancelPolicy": {
          "code": "AD100P_100P",
          "description": "Non Refundable",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        }
      }
    ],
    "bookingChannel": "string",
    "productAddons": [
      {
        "type": "DisneyTicket",
        "code": "code",
        "date": "2018-01-01",
        "quantity": 1,
        "officeId": "string",
        "rate": {
          "ageQualifyingType": {
            "type": "Adult",
            "minAge": 18,
            "maxAge": 99
          },
          "currency": "USD",
          "amountBeforeTax": 123.23,
          "amountAfterTax": 134.34
        }
      }
    ],
    "corpCode": "D_XXX",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  }

PreBook Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	MaxLength: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	MaxLength: 20 Version of API	v4
2	@token	string	Y	MaxLength: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	bookingToken	string	Y	Booking token used for booking	/
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

PreBook Response Example

Success Response (HTTP Status 200)

{
      "header": {
        "supplierId": "HILTON",
        "distributorId": "GTA",
        "version": "v4",
        "token": "18393849028490234"
      },
      "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
      "extensions": {
        "key1": "value1",
        "key2": "value2"
      }
    }

Error Response (HTTP Status 403)

{
      "error": "Key not authorised"
    }

Error Response (HTTP Status 500)

      "errorCode": "string",
      "supplierErrorCode": "string",
      "errorMessage": "string"
    }

Book API

The Book API is used by distributors to reserve rooms in real time. Once a request is sent to the hotel supplier’s system, it processes the reservation and returns immediate confirmation of the booking. This API ensures that the reservation is secured, with the distributor receiving a real-time response, which helps in completing the booking process quickly and accurately. The Book API is a critical step in finalizing reservations, offering a seamless experience for both distributors and customers by providing instant confirmation from the hotel system.

POST /reservation/book HTTP/1.1
URL: {endpoint}/reservation/book
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Book Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds		Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
1	iata	string	N	IATA	/
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	contactPerson	object	Y	/	/
2	@firstName	string	Y	First Name	James
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
2	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	/
2	@adultCount	integer	Y	Adult count per room	/
2	@childCount	integer	N	Child count per room	/
2	@childAges	array	N	For child ages for each child, the array size MUST be the same as the child count.	/
1	total	object	Y	/	/
2	@amountBeforeTax	number	N	abbr. ABT The total room rate for the entire reservation, not including taxes and fees. It's required if AAT is not provided	640
2	@amountAfterTax	number	N	abbr. AAT The total room rate for the entire reservation, including taxes and fees. It's required if ABT is not provided	700
1	payment	object	No	If the credit card information is not going to be passed to the property, this information will be ignored.	/
2	@cardType	string	N	If the payment card type is not specified, it will be treated as the default value "CC" which stands for Credit Card. The type value can be one of the options listed below. CC: Credit Card VCC: Virtual Credit Card CBILL: Central Bill	CC
2	@cardCode	string	Y	VI, MC, AX, etc. Card Code	VI
2	@cardNumber	string	Y	Credit card number	4111111111111111
2	@cardHolderName	string	Y	Cardholder name	Sherlock Holmes
2	@expireDate	string	Y	It should be 2 digits for the month, 2 digits for the year, as "MMYY"	0119
2	@securityCode	string	N	Card verification value	123
2	@vccEffectiveDate	string	N	The effective date of the VCC. Format: yyyy-MM-dd	2025-06-30
2	@vccInvalidDate	string	N	The date when the VCC expires. Format: yyyy-MM-dd	2025-07-30
2	@vccAmountOnCard	number	N	The limit amount of the VCC	1000.00
2	@vccCurrency	string	N	The currency code [ISO-4217] of the amount	USD
1	loyaltyAccount	object	N	/	/
2	@programCode	string	Y	Loyalty program code of the supplier	BW
2	@accountId	string	Y	Loyalty program account ID	1234567890123457
1	corpAccount	object	N	/	/
2	@corpProgramCode	string	Y	Corporate Hotel Program of hotel supplier	CR
2	@corpId	string	Y	Corporate ID in the program account	A-1232
1	promoteCode	string	N	Promotion code defined by the hotel, the promotion code is required if making a reservation under the promotion	/
1	guests	array[object]	Y	/
2	@firstName	string	Y	First Name	James/
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
2	@age	integer	N	Age of guest	/
2	@gender	enum	N	Gender of guest Enum: [Male, Female]	Male
2	@birthday	string	N	Birthday of guest format with yyyy-MM-dd	1970-12-20
2	@type	string	N	Type of guest, Adult, Child, or Infant Enum: [ Adult, Child, Infant ]	/
2	@index	integer	N	Indicate which guests will be allocated to which room. For one room reservation, the room index is 1 for all guests. For multi-room reservations, the index starts from 1 and the max room index is equal to the number of booked rooms.	index = 1, Indicate the guest will allocate to the first room. index = 2, Indicate the guest will allocate to the second room.
2	@extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format).	/
1	comments	array[string]	N	/	[ "no smoking", "high floor" ]
1	roomRates	array[object]	Y	Min Items: 1 Max Items: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API	/
2	@roomId	string	Y	Room ID in supplier's system	10000101
2	@rateId	string	Y	Rate ID in supplier's system	123456
2	@currency	string	Y	Currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	abbr. ABT The daily amount of rate without tax and fee. It's required if AAT is not provided	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	abbr. AAT The daily amount of rate with tax and fee. It's required if ABT is not provided	[ 110, 110, 130 ]
2	@mealPlan	string	N	Meal plan code, refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Indicates the product is prepaid to hotel (PayNow) or pay at hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
1	guarantee	object	N	Guarantee information for this room rate.	/
2	@guaranteeType	string	Y	The type of guarantee method, refer to the standard guarantee type list.	CCG
2	roomRates/fees	array[object]	N	Fee or tax by date range.	/
3	fees/dateRange	object	Y	/	/
4	@startDate	string	Y	Start date of date range, format with yyyy-MM-dd	2018-01-01
4	@endDate	string	Y	End date of date range, format with yyyy-MM-dd	2018-01-04
3	fees/fee		Y	/	/
4	@name	string	Y	Pattern: \w[\w\d]+	Service Charge
4	@type	enum	Y	The fee or tax is included in the amount before tax or not Enum: [ Inclusive, Exclusive ]	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	N	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	/
2	roomRates/cancelPolicy	object	N	Cancellation policy defines what penalty will be a charge when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show.	/
3	@code	string	Y	Max Length: 128 code of cancel policy	AD100P_100P
3	@description	string	N	Max Length: 1024 the description of the cancellation policy	Non Refundable
3	cancelPolicy/cancelPenalties		Y	Detail about the cancel Penalty	/
4	@noShow	boolean	Y	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist	/
4	@cancellable	boolean	N	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
4	cancelPenalties/cancelDeadline	/	/	/	/
5	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
5	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
5	@offsetTimeValue	number	N	The number of offset times with the time unit	/
5	@deadline	string	N	Local deadline times allowed for cancellation, like 4 PM, or 6 PM	/
4	cancelPenalties/penaltyCharge	/	/	/	/
5	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] If FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
5	@nights	number	N	It exists if the penalty charge is based on the night, like the first night.	/
5	@amount	number	N	It exists if the penalty charge is a flat charge, like USD 30.00.	/
5	@percent	number	N	It exists if the penalty charge is percent, like 15.5 means 15.5%.	/
1	bookingChannel	string	N	Sub-distributor ID	/
1	productAddons	array[object]	N	/	/
2	@type	string	Y	product addon type	/
2	@code	string	Y	product addon code	/
2	@date	string	Y	format with yyyy-MM-dd	2022-01-01
2	@quantity	integer	Y	/	1
2	@officeId	string	N	/	/
2	rate	object	N	/	/
3	ageQualifyingType	object	N	/	/
4	@type	enum	Y	Enum: [Adult, Child]	Adult
4	@minAge	string	Y	/	18
4	@maxAge	integer	Y	/	18
2	currency	string	Y	/	USD
2	amountBeforeTax	number	N	/	123.23
2	amountAfterTax	number	N	/	134.34
1	corpCode	string	N	Corporate code in Distributor's system Note: This field is primarily used by Travel Management Companies (TMCs) distributors.	D_XXX
1	threeDomainSecurity	object	N	/	/
2	@cavv	string	N	Cardholder Authentication Verification Value Information is retrieved from the 3DS provider when authentication is successful.	/
2	@eci	string	N	The electronic commerce indicator.	/
2	@xid	string	N	Transaction identifier for a 3DS Version 1 provider, assigned by the Directory Server to identify a single transaction.	/
2	@threeDomainSecurityVersion	string	N	Include this only for 3D Secure 2.	/
2	@transactionId	string	N	Transaction identifier for a 3DS Version 2 provider, assigned by the Directory Server to identify a single transaction.	/
2	@merchantName	string	N	Identifier of the merchant completing the 3DS transaction.	/
2	@channelCode	enum	N	Specify the collection channel of payment cards Enum: [TO, EC, MO, FA] Refer to: PSD2-Channel Code	EC
2	@exemptionType	enum	N	Determines which exemption was used by the Payment Service Provider (PSP) Enum: [SC, DA, TA, TB, LV] Refer to: PSD2-Exemption Type	SC
1	bookingToken	string	Y	Booking token used for booking	/
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Book Request Example

Book Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0"
    },
    "iata": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "contactPerson": {
      "firstName": "Thomas",
      "lastName": "Hintz",
      "email": "Thomas.Hintz@yahoo.com",
      "phone": "260-975-4091",
      "address": "3946 Freddy Locks"
    },
    "roomCriteria": {
      "roomCount": 1,
      "adultCount": 2,
      "childCount": 1,
      "childAges": [
        5
      ]
    },
    "total": {
      "amountBeforeTax": 640,
      "amountAfterTax": 700
    },
    "payment": {
      "cardType": "CC",
      "cardCode": "VI",
      "cardNumber": "4111111111111111",
      "cardHolderName": "Sherlock Holmes",
      "expireDate": "0119",
      "securityCode": "123",
      "vccEffectiveDate": "2018-01-01",
      "vccInvalidDate": "2018-01-02",
      "vccAmountOnCard": 502.19,
      "vccCurrency": "USD"
    },
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "promoteCode": "string",
    "guests": [
      {
        "firstName": "Thomas",
        "lastName": "Hintz",
        "email": "Thomas.Hintz@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 32,
        "gender": "Male",
        "birthday": "1990-01-01",
        "type": "Adult",
        "index": 1,
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "firstName": "Hillary",
        "lastName": "Ullrich",
        "email": "Xavier.Lind49@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 28,
        "gender": "Female",
        "birthday": "1994-01-01",
        "type": "Adult",
        "index": 1
      },
      {
        "firstName": "Alex",
        "lastName": "Hintz",
        "age": 5,
        "type": "Child",
        "index": 1
      }
    ],
    "comments": [
      "no smoking",
      "high floor"
    ],
    "roomRates": [
      {
        "roomId": "K1D",
        "rateId": "ODAD01",
        "currency": "USD",
        "amountBeforeTax": [
          100,
          100,
          120
        ],
        "amountAfterTax": [
          110,
          110,
          130
        ],
        "mealPlan": "RO",
        "paymentType": "PayNow",
        "guarantee": {
          "guaranteeType": "CCG"
        },
        "fees": [
          {
            "dateRange": {
              "startDate": "2018-01-01",
              "endDate": "2018-01-04"
            },
            "fee": {
              "name": "Service Charge",
              "type": "Exclusive",
              "amount": 10,
              "amountType": "Percent",
              "chargeType": "PerRoomPerNight",
              "paymentType": "PayNow",
              "collectBy": "Distributor",
              "effectivePerson": 0
            }
          },
          {
            "dateRange": {
              "startDate": "2018-01-01",
              "endDate": "2018-01-04"
            },
            "fee": {
              "name": "City Tax",
              "type": "Exclusive",
              "amount": 5,
              "amountType": "Fix",
              "chargeType": "PerPersonPerNight",
              "paymentType": "PayLater",
              "collectBy": "Property",
              "effectivePerson": 0
            }
          }
        ],
        "cancelPolicy": {
          "code": "AD100P_100P",
          "description": "Non Refundable",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        }
      }
    ],
    "bookingChannel": "string",
    "productAddons": [
      {
        "type": "DisneyTicket",
        "code": "code",
        "date": "2018-01-01",
        "quantity": 1,
        "officeId": "string",
        "rate": {
          "ageQualifyingType": {
            "type": "Adult",
            "minAge": 18,
            "maxAge": 99
          },
          "currency": "USD",
          "amountBeforeTax": 123.23,
          "amountAfterTax": 134.34
        }
      }
    ],
    "corpCode": "D_XXX",
    "threeDomainSecurity": {
      "cavv": "string",
      "eci": "string",
      "xid": "string",
      "threeDomainSecurityVersion": "string",
      "transactionId": "string",
      "merchantName": "string",
      "channelCode": "EC",
      "exemptionType": "SC",
      "extensions": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  }

Book Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds		Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	N	Reservation ID in DerbySoft system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	N	Reservation ID in supplier's system	89389494
1	connectionType	enum	N	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
1	commission	object	N	Notes: If the connection type is "Exchange" and "Retail" Rate Model, the node will be visible; otherwise, it will not appear.	/
2	@value	number	Y	/	10
2	@type	enum	Y	Commission type Enum: [Percent, Amount]	Percent
1	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
2	@amountBeforeTax	number	N	/	600
2	@amountAfterTax	number	N	/	700
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Book Response Example

Success Response (HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"connectionType": "Exchange",
"commission": {
"value": 10,
"type": "Percent"
},
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"connectionType": "Exchange",
"suggestedTotalPrice": {
"amountBeforeTax": 600,
"amountAfterTax": 700
},
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Error Response (HTTP Status 403)

{
"error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
"errorCode": "string",
"supplierErrorCode": "string",
"errorMessage": "string"
}

Modify API

The Modify API allows distributors to make changes to an existing booking, such as updating travel dates, guest details among others. Upon calling the hotel supplier's system, the API will return a real-time confirmation of the modification. If the hotel supplier or your system does not support direct modifications, the process will instead involve canceling the current booking and rebooking it with the updated details. This functionality provides flexibility in managing reservations, allowing distributors to accommodate customer changes efficiently. For distributors working with certain suppliers, such as Disney, this API is a mandatory requirement to handle modifications seamlessly.

POST /reservation/modify HTTP/1.1
URL: {endpoint}/reservation/modify
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Modification Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of the hotel's source is in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system.	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds		Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	Y	Reservation ID in DerbySoft's system, it's a unique ID as DerbySoft would be splitting the reservation	D15F893D34DF
2	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
1	iata	string	N	IATA	/
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	contactPerson	object	Y	/	/
2	@firstName	string	Y	First Name	James/
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
2	@extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	{ "key": "value"}
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	/
2	@adultCount	integer	Y	Adult count per room	/
2	@childCount	integer	N	Child count per room	/
2	@childAges	array	N	For child ages for each child, array size MUST be the same as the child count.	/
1	total	object	Y	/	/
2	@amountBeforeTax	number	N	The total room rate for the entire reservation, not including taxes and fees.	640
2	@amountAfterTax	number	N	The total room rate for the entire reservation, including taxes and fees.	700
1	payment	object	No	If the credit card information is not going to be passed to the property, this information will be ignored.	/
2	@cardType	string	N	If the payment card type is not specified, it will be treated as the default value "CC" which stands for Credit Card. The type value can be one of the options listed below. CC: Credit Card VCC: Virtual Credit Card CBILL: Central Bill	CC
2	@cardCode	string	Y	VI, MC, AX, etc. Refer to Appendix: Credit Card Code	VI
2	@cardNumber	string	Y	Credit card number	4111111111111111
2	@cardHolderName	string	Y	Cardholder name	Sherlock Holmes
2	@expireDate	string	Y	It should be 2 digits for the month, and 2 digits for the year, as "MMYY"	0119
2	@securityCode	string	N	Card verification value	123
2	@vccEffectiveDate	string	N	The effective date of the VCC. Format: yyyy-MM-dd	2025-06-30
2	@vccInvalidDate	string	N	The date when the VCC expires. Format: yyyy-MM-dd	2025-07-30
2	@vccAmountOnCard	number	N	The limit amount of the VCC	1000.00
2	@vccCurrency	string	N	The currency code [ISO-4217] of the amount	USD
1	loyaltyAccount	object	N	/	/
2	@programCode	string	Y	Loyalty program code of the supplier	BW
2	@accountId	string	Y	Loyalty program account ID	1234567890123457
1	corpAccount	object	N	/	/
2	@corpProgramCode	string	Y	Corporate Hotel Program of hotel supplier	CR
2	@corpId	string	Y	Corporate ID in the program account	A-1232
1	promoteCode	string	N	The promotion code is defined by the hotel, the promotion code is required if making a reservation under the promotion.	/
1	guests	array[object]	Y	/	/
2	@firstName	string	Y	First Name	James
2	@lastName	string	Y	Last Name	Bond
2	@email	string	N	Email	007@james.com
2	@phone	string	N	/	/
2	@address	string	N	/	/
2	@age	integer	N	Age of guest	/
2	@gender	enum	N	Gender of guest Enum: [Male, Female]	/
2	@birthday	string	N	Birthday of guest	/
2	@type	string	N	Type of guest: Adult, Child, or Infant. Enum: [ Adult, Child, Infant ]	/
2	@extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	{ "key": "value"}
2	@index	integer	N	Indicate which guests will be allocated to which room. For one room reservation, the room index is 1 for all guests. For multi-room reservations, the index starts from 1 and the max room index is equal to the number of booked rooms.	index = 1, Indicate the guest will allocate to the first room. index = 2, Indicate the guest will allocate to the second room.
2	@extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format).
1	comments	array[string]	N	/	[ "no smoking", "high floor" ]
1	roomRates	array[object]	Y	Min Items: 1 max Item: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
2	@roomId	string	Y	Room ID in supplier system	10000101
2	@rateId	string	Y	Rate ID in supplier system	123456
2	@currency	string	Y	currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	The daily amount rate without tax and fee	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	The daily amount of rate with tax and fee	[ 110, 110, 130 ]
2	@mealPlan	string	N	Meal plan code, refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
2	roomRates/guarantee	object	N	Guarantee information for this room rate	/
3	@guaranteeType	string	Y	The type of guarantee method, refer to the standard guarantee type list.	CCG
2	roomRates/fees	array[object]	N	Fee or tax by date range	/
3	fees / dateRange	object	Y	/	/
4	@startDate	string	Y	Start date of date range, format with yyyy-MM-dd	2018-01-01
4	@endDate	string	Y	End date of date range, format with yyyy-MM-dd	2018-01-04
3	fees/fee		Y	/	/
4	@name	string	Y	Pattern: \w[\w\d]+	Service Charge
4	@type	enum	Y	Whether the fee or tax is included in the amount before tax or not Enum: [ Inclusive, Exclusive ]	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Indicates how to charge the tax, 10% per room per night in this example. Enum: [ Fix, Percent ]	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	No	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.
2	roomRates / cancelPolicy	object	N	The cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show.	/
3	@code	string		Max Length: 128 Code of cancellation policy	AD100P_100P
3	@description	string		Max Length: 1024 the description of the cancellation policy	Non Refundable
1	bookingChannel	string	N	Sub-distributor ID	/
1	productAddons	array[object]	N
2	@type	string	Y	product addon type
2	@code	string	Y	product addon code
2	@date	string	Y	format with yyyy-MM-dd	2022-01-01
2	@quantity	integer	Y	/	1
2	@officeId	string	N	/	/
2	rate	object	N	/	/
3	ageQualifyingType	object	N	/	/
4	@type	enum	Y	Enum: [Adult, Child]	Adult
4	@minAge	integer	Y	/	18
4	@maxAge	integer	Y	/	18
3	currency	string	Y	/	USD
3	amountBeforeTax	number	N	/	123
3	amountAfterTax	number	Y	/
1	corpCode	string	N	Corporate code in Distributor's system Note: This field is primarily used by Travel Management Companies (TMCs) distributors.	D_XXX
1	threeDomainSecurity	object	N	/	/
2	@cavv	string	N	Cardholder Authentication Verification Value Information is retrieved from the 3DS provider when authentication is successful.	/
2	@eci	string	N	The electronic commerce indicator.	/
2	@xid	string	N	Transaction identifier for a 3DS Version 1 provider, assigned by the Directory Server to identify a single transaction.	/
2	@threeDomainSecurityVersion	string	N	Include this only for 3D Secure 2.	/
2	@transactionId	string	N	Transaction identifier for a 3DS Version 2 provider, assigned by the Directory Server to identify a single transaction.	/
2	@merchantName	string	N	Identifier of the merchant completing the 3DS transaction.	/
2	@channelCode	enum	N	Specify the collection channel of payment cards Enum: [TO, EC, MO, FA] Refer to: PSD2-Channel Code	EC
2	@exemptionType	enum	N	Determines which exemption was used by the Payment Service Provider (PSP) Enum: [SC, DA, TA, TB, LV] Refer to: PSD2-Exemption Type	SC
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Modification Request Example

Modification Request example

{
        "header": {
          "supplierId": "HILTON",
          "distributorId": "GTA",
          "version": "v4",
          "token": "18393849028490234"
        },
        "reservationIds": {
          "distributorResId": "C2084DFL0",
          "derbyResId": "D15F893D34DF",
          "supplierResId": "89389494"
        },
        "iata": "string",
        "hotelId": "GATHI",
        "stayRange": {
          "checkin": "2018-01-01",
          "checkout": "2018-01-04"
        },
        "contactPerson": {
          "firstName": "Thomas",
          "lastName": "Hintz",
          "email": "Thomas.Hintz@yahoo.com",
          "phone": "260-975-4091",
          "address": "3946 Freddy Locks"
        },
        "roomCriteria": {
          "roomCount": 1,
          "adultCount": 2,
          "childCount": 1,
          "childAges": [
            5
          ]
        },
        "total": {
          "amountBeforeTax": 640,
          "amountAfterTax": 700
        },
        "payment": {
          "cardType": "CC",
          "cardCode": "VI",
          "cardNumber": "4111111111111111",
          "cardHolderName": "Sherlock Holmes",
          "expireDate": "0119",
          "securityCode": "123",
          "vccEffectiveDate": "2018-01-01",
          "vccInvalidDate": "2018-01-02",
          "vccAmountOnCard": 502.19,
          "vccCurrency": "USD"
        },
        "loyaltyAccount": {
          "programCode": "BW",
          "accountId": "1234567890123457"
        },
        "corpAccount": {
          "corpProgramCode": "CR",
          "corpId": "A-1232"
        },
        "promoteCode": "string",
        "guests": [
          {
            "firstName": "Thomas",
            "lastName": "Hintz",
            "email": "Thomas.Hintz@yahoo.com",
            "phone": "260-975-4091",
            "address": "3946 Freddy Locks",
            "age": 32,
            "gender": "Male",
            "birthday": "1990-01-01",
            "type": "Adult",
            "index": 1
          },
          {
            "firstName": "Hillary",
            "lastName": "Ullrich",
            "email": "Xavier.Lind49@yahoo.com",
            "phone": "260-975-4091",
            "address": "3946 Freddy Locks",
            "age": 28,
            "gender": "Female",
            "birthday": "1994-01-01",
            "type": "Adult",
            "index": 1,
            "extensions": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          {
            "firstName": "Alex",
            "lastName": "Hintz",
            "age": 5,
            "type": "Child",
            "index": 1
          }
        ],
        "comments": [
          "no smoking",
          "high floor"
        ],
        "roomRates": [
          {
            "roomId": "K1D",
            "rateId": "ODAD01",
            "currency": "USD",
            "amountBeforeTax": [
              100,
              100,
              120
            ],
            "amountAfterTax": [
              110,
              110,
              130
            ],
            "mealPlan": "RO",
            "paymentType": "PayNow",
            "guarantee": {
              "guaranteeType": "CCG"
            },
            "fees": [
              {
                "dateRange": {
                  "startDate": "2018-01-01",
                  "endDate": "2018-01-04"
                },
                "fee": {
                  "name": "Service Charge",
                  "type": "Exclusive",
                  "amount": 10,
                  "amountType": "Percent",
                  "chargeType": "PerRoomPerNight",
                  "paymentType": "PayNow",
                  "collectBy": "Distributor",
                  "effectivePerson": 0
                }
              },
              {
                "dateRange": {
                  "startDate": "2018-01-01",
                  "endDate": "2018-01-04"
                },
                "fee": {
                  "name": "City Tax",
                  "type": "Exclusive",
                  "amount": 5,
                  "amountType": "Fix",
                  "chargeType": "PerPersonPerNight",
                  "paymentType": "PayLater",
                  "collectBy": "Property",
                  "effectivePerson": 0
                }
              }
            ],
            "cancelPolicy": {
              "code": "AD100P_100P",
              "description": "Non Refundable",
              "cancelPenalties": [
                {
                  "noShow": true,
                  "cancellable": true,
                  "cancelDeadline": {
                    "offsetTimeDropType": "BeforeArrival",
                    "offsetTimeUnit": "D",
                    "offsetTimeValue": 0,
                    "deadline": "string"
                  },
                  "penaltyCharge": {
                    "chargeBase": "FullStay",
                    "nights": 0,
                    "amount": 0,
                    "percent": 0
                  }
                }
              ]
            }
          }
        ],
        "bookingChannel": "string",
        "productAddons": [
          {
            "type": "DisneyTicket",
            "code": "code",
            "date": "2018-01-01",
            "quantity": 1,
            "officeId": "string",
            "rate": {
              "ageQualifyingType": {
                "type": "Adult",
                "minAge": 18,
                "maxAge": 99
              },
              "currency": "USD",
              "amountBeforeTax": 123.23,
              "amountAfterTax": 134.34
            }
          }
        ],
        "corpCode": "D_XXX",
        "threeDomainSecurity": {
          "cavv": "string",
          "eci": "string",
          "xid": "string",
          "threeDomainSecurityVersion": "string",
          "transactionId": "string",
          "merchantName": "string",
          "channelCode": "EC",
          "exemptionType": "SC",
          "extensions": {
            "key1": "value1",
            "key2": "value2"
          }
        },
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      }

Modification Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of hotel suppliers in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds	object	Y	/	100001
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	Y	Reservation ID in DerbySoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
1	connectionType	enum	N	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
1	commission	object	N	Notes: If the connection type is "Exchange" and "Retail" Rate Model, the node will be visible; otherwise, it will not appear.	/
2	@value	number	Y	/	10
2	@type	enum	Y	Commission type Enum: [Percent, Amount]	Percent
1	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
2	@amountBeforeTax	number	No	/	600
2	@amountAfterTax	number	Y	/	700
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Modification Response Example

Success Response (HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"extensions": {
"key": "value"
}
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"connectionType": "Exchange",
"commission": {
"value": 10,
"type": "Percent"
},
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"connectionType": "Exchange",
"suggestedTotalPrice": {
"amountBeforeTax": 600,
"amountAfterTax": 700
},
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Error Response (HTTP Status 403)

{
"error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
"errorCode": "string",
"supplierErrorCode": "string",
"errorMessage": "string"
}

Cancellation API

The Cancel API enables distributors to send cancellation requests to DerbySoft, which then communicates with the hotel suppliers’ systems to cancel the booking in real time. This ensures a smooth and efficient cancellation process. For non-multiroom bookings, using the supplierResId is sufficient to trigger the cancellation. However, for multi-room reservations, both the derbyResId and supplierResId must be used, as DerbySoft handles the splitting of original reservations in these cases. Once the cancellation request is sent, distributors receive immediate confirmation from the supplier’s system, ensuring the cancellation is processed and accurately reflected. This functionality is essential for managing booking changes, giving distributors the ability to process customer cancellations quickly and confidently.

POST /reservation/cancel HTTP/1.1
URL: {endpoint}/reservation/cancel
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Cancellation Request Schema

Request
Level	Field Name	Required	Data Type	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of hotel supplier in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system.	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds	object	Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	No	Reservation ID in DerbySoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	No	Reservation ID in supplier's system	89389494
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	{"key": "value"}

Cancellation Request Example

Cancellation Request Example

{
        "header": {
            "supplierId": "HILTON",
            "distributorId": "GTA",
            "version": "v4",
            "token": "18393849028490234"
        },
        "reservationIds": {
            "distributorResId": "C2084DFL0",
            "derbyResId": "D15F893D34DF",
            "supplierResId": "89389494"
        },
        "extensions": {
            "key1": "value1",
            "key2": "value2"
        }
      }

Cancellation Response Schema

Response
Level	Field Name	Required	Data Type	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of hotel suppliers is in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds	object	Y	/	100001
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	Y	Reservation ID in DerbySoft's system, It's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
2	cancellationId	string	Y	Cancellation confirmation number in supplier's system	C89389494
1	extensions	object	N	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format)	/

Cancellation Response Example

Success Response (HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"cancellationId": "C89389494",
"extensions": {
"key1": "value1",
"key2": "value2"
}
}

Error Response (HTTP Status 403)

{
"error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
"errorCode": "string",
"supplierErrorCode": "string",
"errorMessage": "string"
}

Query Reservation List API

The Query Reservation List API allows distributors to retrieve a list of reservations from both DerbySoft's system and the hotel supplier's system. The query is based on a specified date range of the reservation’s last modified date, ensuring that only relevant and updated reservation information is fetched. This API is essential for managing and tracking reservations over time, providing distributors with up-to-date insights into their bookings. To ensure proper functionality, both DerbySoft and the hotel supplier must implement this API. By doing so, distributors can query reservations across both systems, offering a comprehensive view of reservation statuses and updates, which is crucial for effective booking management.

POST /reservations HTTP/1.1
URL: {endpoint}/reservations
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Reservation List Request Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/
2	@supplierId	string	Y	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	dateRange	/	/	Date range of last modified date of reservation	/
2	@startDate	string	Y	Start date of date range Format: yyyy-MM-dd	2018-01-01
2	@endDate	string	Y	End date of the date range Format: yyyy-MM-dd	2018-01-04
1	hotelId	string	N	Supplier hotel ID in DerbySoft's system	GATHI

Reservation List Request Example

Reservation List Request Example

{
        "header": {
          "supplierId": "HILTON",
          "distributorId": "GTA",
          "version": "v4",
          "token": "18393849028490234"
        },
        "dateRange": {
          "startDate": "2018-01-01",
          "endDate": "2018-01-04"
        },
        "hotelId": "GATHI"
      }

Reservation List Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservations	array[object]	No	/	/
2	reservationIds	object	No	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	Y	Reservation ID in DerbySoft's system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
1	@iata	string	N	/	/
1	@hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	roomCriteria	object	Y	/
2	@roomCount	integer	Y	Total room count per request
2	@adultCount	integer	Y	Adult count per room
2	@childCount	integer	N	Child count per room
2	@childAges	array	N	For child ages for each child, array size MUST be the same as the child count.	[ 4, 8 ]
2	connectionType	enum	No	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
2	total	object	Y	/	/
3	@amountBeforeTax	number	N	/	640
3	@amountAfterTax	number	N	/	700
2	commission	object	N	Notes: If the connection type is "Exchange" and "Retail" Rate Model, the node will be visible; otherwise, it will not appear.	/
3	@value	number	Y	/	10
3	@type	enum	Y	Commission type Enum: [Percent, Amount]	Percent
2	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
3	@amountBeforeTax	number	N	/	600
3	@amountAfterTax	number	N	/	700
2	@status	enum	Y	Enum: [ Confirmed, Modified, Cancelled ] Status of reservation	/
2	cancellationId	string	N	Cancel confirmation number in supplier's system	C89389494
2	@result	enum	Y	Enum: [ Successful, Failed, Processing ] Status of the reservation to send to supplier	/
2	failCause	object	No	Note: If the reservation fails, the node will be visible; otherwise, it will not appear.	/
3	@errorCode	string	Y	Refer to Error Code Appendix	/
3	@supplierErrorCode	string	N	Error code from the supplier's system	/
3	@errorMessage	string	Y	Error message	/

Reservation List Response Example

Success Response (HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservations": [
{
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"iata": "string",
"hotelId": "GATHI",
"stayRange": {
"checkin": "2018-01-01",
"checkout": "2018-01-04"
},
"roomCriteria": {
"roomCount": 2,
"adultCount": 1,
"childCount": 2,
"childAges": [
4,
8
]
},
"total": {
"amountBeforeTax": 640,
"amountAfterTax": 700
},
"status": "Confirmed",
"cancellationId": "C89389494",
"result": "Successful",
"failCause": {
"errorCode": "string",
"supplierErrorCode": "string",
"errorMessage": "string"
}
}
]
}

Successful Response from Exchange Connection and Retail Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservations": [
{
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"iata": "string",
"hotelId": "GATHI",
"stayRange": {
"checkin": "2018-01-01",
"checkout": "2018-01-04"
},
"contactPerson": {
"firstName": "James",
"lastName": "Bond",
"email": "007@james.com",
"phone": "string",
"address": "string"
},
"roomCriteria": {
"roomCount": 2,
"adultCount": 1,
"childCount": 2,
"childAges": [
4,
8
]
},
"connectionType": "Exchange",
"total": {
"amountBeforeTax": 640,
"amountAfterTax": 700
},
"commission": {
"value": 10,
"type": "Percent"
},
"status": "Confirmed",
"cancellationId": "C89389494",
"result": "Successful"
}
]
}

Successful Response from Exchange Connection and Net Rate Model(HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservations": [
{
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"iata": "string",
"hotelId": "GATHI",
"stayRange": {
"checkin": "2018-01-01",
"checkout": "2018-01-04"
},
"contactPerson": {
"firstName": "James",
"lastName": "Bond",
"email": "007@james.com",
"phone": "string",
"address": "string"
},
"roomCriteria": {
"roomCount": 2,
"adultCount": 1,
"childCount": 2,
"childAges": [
4,
8
]
},
"connectionType": "Exchange",
"total": {
"amountBeforeTax": 640,
"amountAfterTax": 700
},
"suggestedTotalPrice": {
"amountBeforeTax": 600,
"amountAfterTax": 700
},
"status": "Confirmed",
"cancellationId": "C89389494",
"result": "Successful"
}
]
}

Error Response (HTTP Status 403)

{
"error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
"errorCode": "InvalidField",
"errorMessage": "Invalid Message"
}

Query Reservation Details API

The Query Reservation Detail API allows distributors to retrieve detailed information about existing bookings, including the current status of the reservation. The possible statuses include confirmed, modified, or cancelled, helping distributors track the progress and changes to the booking. This API provides a comprehensive view of individual reservations, allowing distributors to access key details such as guest information, room types, booking dates, and other important data. This API is essential for efficient reservation management, giving distributors the ability to stay informed about the status and details of each booking, enabling them to take appropriate actions when necessary.

POST /reservations HTTP/1.1
URL: {endpoint}/reservations
Authorization: 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Reservation Details Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 The ID of the hotel supplier in DerbySoft's system.	HILTON
2	@distributorId	string	Y	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	Max Length: 20 Version of API	v4
2	@token	string	Y	Max Length: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservationIds	object	Y	/	/
2	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
2	@derbyResId	string	N	Reservation ID in DerbySoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
2	@supplierResId	string	N	Reservation ID in supplier's system	89389494

Reservation Details Request Example

Reservation Details Request Example

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    }
  }

Reservation Details Response Schema

Response
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
2	@distributorId	string	Y	MaxLength: 32 The ID of the distributor in DerbySoft's system	GTA
2	@version	string	Y	MaxLength: 20 version of API	v4
2	@token	string	Y	MaxLength: 64 A unique identifier is used for requests and responses, typically a UUID. Note that this is an echo token, not an access token.	18393849028490234
1	reservations	array[object]	N	/	/
2	reservationIds	object	N	/	/
3	@distributorResId	string	Y	Distributor's reservation ID. Distributors should keep the ID unique on their system to avoid any potential issues caused by duplicate reservation IDs.	C2084DFL0
3	@derbyResId	string	Y	Reservation ID in DerbySoft system, This is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
3	@supplierResId	string	Y	Reservation ID in supplier's system	89389494
1	iata	string	N	/	/
1	hotelId	string	Y	Hotel IDs provided by hotel suppliers, only the following characters are allowed. 1. Digits (0-9) 2. Uppercase letters (A-Z) 3. Hyphen ('-')	100001 GATHI 00016 PEP-B3T2 B8W7
1	stayRange	object	Y	/	/
2	@checkin	string	Y	Check-in, format with yyyy-MM-dd	2018-01-01
2	@checkout	string	Y	Check out, format with yyyy-MM-dd	2018-01-04
1	roomCriteria	object	Y	/	/
2	@roomCount	integer	Y	Total room count per request	/
2	@adultCount	integer	Y	Adult count per room	/
2	@childCount	integer	N	Child count per room
2	@childAges	array	N	For child ages each child, the array size MUST be the same as the child count.	/
1	connectionType	enum	N	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the field is omitted, it means the Connection Type is Standard.	Exchange
1	total	object	Y	/	/
2	@amountBeforeTax	number	N	/	640
2	@amountAfterTax	number	N	/	700
1	commission	object	N	If the Connection Type is "Exchange" and the Rate Model is "Retail", the node will be visible; otherwise, it will disappear.	/
2	@value	number	N	/	10
2	@type	enum	N	Commission type Enum: [Percent, Amount]	Percent
1	suggestedTotalPrice	object	N	Notes: If the connection type is "Exchange" and "Net" Rate Model, the node will be visible; otherwise, it will not appear.	/
2	@amountBeforeTax	number	N	/	600
2	@amountAfterTax	number	N	/	700
1	loyaltyAccount	object	N	/	/
2	@programCode	string	Y	The loyalty program code of the supplier	BW
2	@accountId	string	Y	Loyalty program account ID	1234567890123457
1	corpAccount	object	N	/	/
2	@corpProgramCode	string	Y	Corporate Hotel Program of hotel supplier	CR
2	@corpId	string	Y	Corporate ID in the program account	A-1232
1	promoteCode	string	N	The promotion code is defined by the hotel, the promotion code is required if making a reservation under the promotion.	/
1	comments	array[string]	N	/	[ "no smoking", "high floor" ]
1	roomRates	array[object]	Y	Min Items: 1 Max Item: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
2	@roomId	string	Y	Room ID in supplier's system	10000101
2	@rateId	string	Y	Rate ID in supplier's system	123456
2	@currency	string	Y	Currency code [ISO-4217]	USD
2	@amountBeforeTax	array[number]	N	The daily amount rate without tax and fee	[ 100, 100, 120 ]
2	@amountAfterTax	array[number]	N	The daily amount of rate with tax and fee	[ 110, 110, 130 ]
2	@mealPlan	string	N	Meal plan code, refer to the standard meal plan code list.	RO
2	@paymentType	enum	N	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
2	guarantee	object	N	Guarantee information for this room rate.	/
3	@guaranteeType	string	Y	The type of guarantee method, refers to the standard guarantee type list.	CCG
2	fees	array[object]	N	Fee or tax by date range.	/
3	dateRange	object	Y	/	/
4	@startDate	string	Y	Start date of date range, format with yyyy-MM-dd	2018-01-01
4	@endDate	string	Y	End date of date range, format with yyyy-MM-dd	2018-01-04
3	fees/fee	object	Y	/	/
4	@name	string	Y	Pattern: \w[\w\d]+	Service Charge
4	@type	enum	Y	Indicates if the fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
4	@amount	number	Y	Amount value of fee or tax	10
4	@amountType	string	Y	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
4	@chargeType	string	Y	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
4	@paymentType	enum	N	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater). Note: The 'paymentType' field will be replaced by 'collectBy' and removed from the API in the future.	PayNow
4	@collectBy	enum	N	Enum: [Distributor, Property] Indicates that the fee (e.g., City Tax, Tourist Tax) should be collected by the hotel(Property) at check-in or by distributors when guests make a reservation(Distributor).	Distributor
4	@effectivePerson	number	N	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	/
2	cancelPolicy	object	N	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show.	/
3	@code	string	Y	Max Length: 128 Code of cancel policy	AD100P_100P
3	@description	string	N	Max Length: 1024 The description of the cancellation policy	Non Refundable
3	cancelPenalties		Y	Detail about the canceled Penalty	/
4	@noShow	boolean	Y	If true, it means the penalty charge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
4	@cancellable	boolean	N	Indicates if cancellation is allowed or not. If false, it cannot be canceled. If true, the cancellation deadline will exist.	/
4	cancelDeadline	object	N	/	/
5	@offsetTimeDropType	enum	N	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
5	@offsetTimeUnit	enum	N	Enum: [ D, H ]	/
5	@offsetTimeValue	number	N	The number of offset times with the time unit	/
5	@deadline	string	N	Local deadline times allowed for cancellation, like 4 PM, or 6 PM.	/
4	penaltyCharge	object	N	/	/
5	@chargeBase	enum	N	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
5	@nights	number	No	It exists if the penalty charge is based on the night, like the first night.	/
5	@amount	number	No	It exists if the penalty charge is a flat charge, like USD 30.00.	/
5	@percent	number	No	It exists if the penalty charge is percent, like 15.5 means 15.5%	/
1	bookingChannel	string	N	Sub-distributor ID	/
1	productAddons	array[object]	N	/	/
2	@type	string	Y	/	DisneyTicket
2	@code	string	Y	/	/
2	@date	string	Y	format with yyyy-MM-dd	2022-01-01
2	@quantity	integer	Y	/	1
2	@officeId	string	N	specific distributor office	/
2	productAddons/rate	object	N	/	/
3	ageQualifyingType	object	N	/	/
4	@type	enum	Y	Enum: [Adult, Child]	Adult
4	@minAge	integer	Y	/	18
4	@maxAge	integer	Y	/	18
3	currency	string	Y	/	USD
3	amountBeforeTax	number	N	/	123.23
3	amountAfterTax	number	N	/	134.34
2	status	enum	Y	Enum: [ Confirmed, Modified, Cancelled ] The latest status of the reservation Confirmed - New reservation Modified - Modification Reservation Cancelled - Cancellation Reservation Please combine the status and result fields to determine the reservation whether successful, combination examples are as follows: Confirmed + Successful = Booking is successful Confirmed + Failed = Booking is failed Modified + Successful = Modification is successful Modified + Failed = Modification is failed Cancelled + Successful = Cancellation is successful Cancelled + Failed = Cancellation is failed	/
2	cancellationId	string	N	Cancellation confirmation number in suppliers' system	C89389494
2	result	enum	Y	Enum: [ Successful, Failed, Processing ] result of the reservation to send to the supplier	/
2	failCause	object	N	Note: If the reservation fails, the node will be visible; otherwise, it will not appear.	/
3	@errorCode	string	Y	Error Code Appendix	/
3	@supplierErrorCode	string	N	Error code from the supply system	/
3	@errorMessage	string	Y	Error message	/

Reservation Details Response Example

Success Response (HTTP Status 200)

{
"header": {
"supplierId": "HILTON",
"distributorId": "GTA",
"version": "v4",
"token": "18393849028490234"
},
"reservations": [
{
"reservationIds": {
"distributorResId": "C2084DFL0",
"derbyResId": "D15F893D34DF",
"supplierResId": "89389494"
},
"iata": "string",
"hotelId": "GATHI",
"stayRange": {
"checkin": "2018-01-01",
"checkout": "2018-01-04"
},
"roomCriteria": {
"roomCount": 2,
"adultCount": 1,
"childCount": 2,
"childAges": [
4,
8
]
},
"connectionType": "Exchange",
"total": {
"amountBeforeTax": 640,
"amountAfterTax": 700
},
"commission": {
"value": 10,
"type": "Percent"
},
"suggestedTotalPrice": {
"amountBeforeTax": 600,
"amountAfterTax": 700
},
"loyaltyAccount": {
"programCode": "BW",
"accountId": "1234567890123457"
},
"corpAccount": {
"corpProgramCode": "CR",
"corpId": "A-1232"
},
"promoteCode": "string",
"comments": [
"no smoking",
"high floor"
],
"roomRates": [
{
"roomId": "K1D",
"rateId": "ODAD01",
"currency": "USD",
"amountBeforeTax": [
100,
100,
120
],
"amountAfterTax": [
110,
110,
130
],
"mealPlan": "RO",
"paymentType": "PayNow",
"guarantee": {
"guaranteeType": "CCG"
},
"fees": [
{
"dateRange": {
"startDate": "2018-01-01",
"endDate": "2018-01-04"
},
"fee": {
"name": "Service Charge",
"type": "Exclusive",
"amount": 10,
"amountType": "Percent",
"chargeType": "PerRoomPerNight",
"paymentType": "PayNow",
"collectBy": "Distributor",
"effectivePerson": 0
}
},
{
"dateRange": {
"startDate": "2018-01-01",
"endDate": "2018-01-04"
},
"fee": {
"name": "City Tax",
"type": "Exclusive",
"amount": 5,
"amountType": "Fix",
"chargeType": "PerPersonPerNight",
"paymentType": "PayLater",
"collectBy": "Property",
"effectivePerson": 0
}
}
],
"cancelPolicy": {
"code": "AD100P_100P",
"description": "Non Refundable",
"cancelPenalties": [
{
"noShow": true,
"cancellable": true,
"cancelDeadline": {
"offsetTimeDropType": "BeforeArrival",
"offsetTimeUnit": "D",
"offsetTimeValue": 0,
"deadline": "string"
},
"penaltyCharge": {
"chargeBase": "FullStay",
"nights": 0,
"amount": 0,
"percent": 0
}
}
]
}
}
],
"bookingChannel": "string",
"productAddons": [
{
"type": "DisneyTicket",
"code": "code",
"date": "2018-01-01",
"quantity": 1,
"officeId": "string",
"rate": {
"ageQualifyingType": {
"type": "Adult",
"minAge": 18,
"maxAge": 18
},
"currency": "USD",
"amountBeforeTax": 123.23,
"amountAfterTax": 134.34
}
}
],
"status": "Confirmed",
"cancellationId": "C89389494",
"result": "Successful",
"failCause": {
"errorCode": "string",
"supplierErrorCode": "string",
"errorMessage": "string"
}
}
]
}

Error Response (HTTP Status 403)

{
"error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
"errorCode": "InvalidField",
"errorMessage": "Invalid Message"
}

Audit API

The Audit API allows GO to push reservation audit data to GO Distributors, providing real-time updates on guest stay status, including check-ins, check-outs, and no-shows. This API ensures that distributors receive accurate and timely information about the status of each reservation. However, please note that only a limited number of hotel suppliers support the provision of audit data to GO. Before implementing the Audit API, it is recommended to check with us to confirm whether your hotel suppliers offer this functionality.

Audit Request Schema

Request(METHOD: POST)
Level	Field Name	Data Type	Required	Description	Example
1	header	object	Y	/	/
2	@distributorId	string	Y	Distributor's ID Max Length: 32	HUAWEI
2	@supplierId	string	Y	Supplier's ID Max Length: 32	HUAZHU
2	@token	string	Y	/	/
1	hotelId	string	Y	Supplier Hotel ID	100001
1	reservationId	object	Y	/	/
2	@distributorResId	string	Y	Reservation ID of Distributor	C2084DFL0
2	@derbyResId	string	Y	Reservation ID of DerbySoft	D15F893D34DF
2	@supplierResId	string	Y	Reservation ID of Hotel Supplier	89389494,89389495
1	auditId	string	Y	Audit record ID	9f1925cc888c438d
1	auditDateTime	string	Y	The time when GO received the request from Hotel Suppliers	2023-06-04T08:12:23.123Z
1	currency	string	Y	Currency Code【ISO-4217】	USD
1	roomDetails	array[object]	Y	There would be multiple rooms	/
2	@roomId	string	Y	Room ID	10000101
2	@rateId	string	Y	Rate Plan ID	123456
2	@roomStatus	enum	Y	Eunm: [NO_SHOW, CHECK_IN, CHECK_OUT]	/
2	@hotelComments	string	No	Comments by Hotel Supplier	/
2	@supplierResId	string		If the supplier has split the order for multiple rooms, here it represents the sub-order number for the supplier.	89389494
2	stayDateRange	object	No	Actual time of check-in/check-out	/
3	@checkInDateTime	string	Y	Guest check-in datetime	2023-06-04T08:12:23.123Z
3	@checkOutDateTime	string	Y	Guest check-in datetime	2023-06-04T08:12:23.123Z
3	@timeZone	string	No	Time Zone	/
2	roomRevenue	object	No	Room cost	/
3	@amountBeforeTax	number	No	Amount Before tax	/
3	@amountAfterTax	number	No	Amount After tax	/
2	otherFees	array[object]	No	/	/
3	@amountBeforeTax	number	No	Amount Before Tax	/
3	@amountAfterTax	number	No	Amount After Tax	/
3	@description	string	No	Description of Fees	/
1	total	object	No	/	/
2	roomRevenue	object	No	Total Order Cost	/
2	@amountBeforeTax	number	No	Amount Before Tax	/
2	@amountAfterTax	number	No	Amount After Tax	/
2	otherFees	array[object]	No	Other fees	/
3	@amountBeforeTax	number	No	Amount Before Tax	/
3	@amountAfterTax	number	No	Amount After Tax	/
3	@description	string	No	Description of Fees	/

Audit Request Example

Audit Request Example

{
    "header": {
        "distributorId": "xxx",
        "supplierId": "xxx",
        "token": "xxx"
    },
    "hotelId": "hotelCode",
    "reservationId": {
        "distributorResId": "xxx",
        "derbyResId": "xxx",
        "supplierResId": "supplierResId1,supplierResId2"
    },
    "auditId": "xx",
    "auditDateTime": "2023-06-04T08:12:23.123Z",
    "currency": "CNY",
    "roomDetails": [
        {
            "roomId": "100001",
            "rateId": "123456",
            "stayDateRange": {
                "checkInDateTime": "2023-06-01 08:12:23",
                "checkOutDateTime": "2023-06-03 08:12:23",
                "timeZone": ""
            },
            "roomStatus": "CHECK_IN",
            "roomRevenue": {
                "amountBeforeTax": 250,
                "amountAfterTax": 450
            },
            "otherFees": [
                {
                    "amountBeforeTax": 3,
                    "amountAfterTax": 5,
                    "description": "Drink"
                }
            ],
            "hotelComments": "Comments from hotel side",
            "supplierResId": "supplierResID1"
        }
    ],
    "total": {
        "roomRevenue": {
            "amountBeforeTax": 250,
            "amountAfterTax": 450
        },
        "otherFees": [
            {
                "amountBeforeTax": 20,
                "amountAfterTax": 40,
                "description": "Drink Fee"
            },
            {
                "amountBeforeTax": 50,
                "amountAfterTax": 70,
                "description": "Penalty"
            },
            {
                "amountBeforeTax": 40,
                "amountAfterTax": 50,
                "description": "ServiceCharge"
            }
        ]
    }
}

Audit Response Schema

Response
Level	Field Name	Required	Data Type	Description	Example
1	header	object	Y	/	/
2	@supplierId	string	Y	Max Length: 32 Hotel Supplier's ID	HUAZHU
2	@distributorId	string	Y	Max Length: 32 Distributor's ID	HUAWEI
2	@token	string	Y	Max Length: 64 It is recommended to use a Universally Unique Identifier (UUID) as a unique identifier for requests and responses. This will ensure that each request and response is uniquely identified and can be tracked efficiently.	18393849028490234
1	result	string	Y	/	Success

Audit Response Example

Success Response (HTTP Status 200)

{
        "header": {
            "distributorId": "xxx",
            "supplierId": "xxx",
            "token": "xxx"
        },
        "result": "Success"
    }

Error Response (HTTP Status 401)

{
        "errorCode": "InvalidIdentityCredential",
        "errorMessage": "Invalid Identity Credential"
    }

Error Response (HTTP Status 500)

{
        "errorCode": "InternalError",
        "errorMessage": "error message with details of the error"
    }

English

Reservation APIs

Reservation API Introduction

Key Functionalities of the Reservation API

Reservation Flow overview

Live check API

Live Check Request Schema

Live Check Request Example

Live Check Response Schema

Live Check Response Example

PreBook API

PreBook Request Schema

PreBook Request Example

PreBook Response Schema

PreBook Response Example

Book API

Book Request Schema

Book Request Example

Book Response Schema

Book Response Example

Modify API

Modification Request Schema

Modification Request Example

Modification Response Schema

Modification Response Example

Cancellation API

Cancellation Request Schema

Cancellation Request Example

Cancellation Response Schema

Cancellation Response Example

Query Reservation List API

Reservation List Request Schema

Reservation List Request Example

Reservation List Response Schema

Reservation List Response Example

Query Reservation Details API

Reservation Details Request Schema

Reservation Details Request Example

Reservation Details Response Schema

Reservation Details Response Example

Audit API

Audit Request Schema

Audit Request Example

Audit Response Schema

Audit Response Example